home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / dev / debug / Sashimi.lha / sashimi.doc next >
Encoding:
Text File  |  1998-09-12  |  7.7 KB  |  210 lines
  1. Sashimi v1.4
  2.  
  3. Written by Olaf `Olsen' Barthel <olsen@sourcery.han.de>
  4. Public Domain
  5.  
  6.  
  7. Sashimi intercepts raw serial debugging output on your own machine; command
  8. line options are:
  9.  
  10. Startup: [ON] [BUFK=n (n must be a power of 2)] [BUFFERSIZE=n] [NOPROMPT]
  11.          [QUIET] [ASKEXIT] [ASKSAVE] [TIMERON] [CONSOLE] [WINDOW=name]
  12.  
  13. Runtime: [OFF] [SAVE] [SAVEAS=name] [EMPTY]
  14.  
  15.  
  16. Sashimi is a tool to intercept the raw serial output of Enforcer, Mungwall,
  17. and all tool and application debugging output that uses kprintf(). This
  18. makes it possible to use serial debugging on a single Amiga, without
  19. interfering with attached serial hardware such as modems and serial
  20. printers.
  21.  
  22. This is a drop-in replacement for the "Sushi" tool, as written by Carolyn
  23. Scheppner. Well, not exactly. Sashimi has a few different/new features and
  24. does not support the complete feature set of the "Sushi" tool. Sashimi only
  25. runs from Shell and requires Kickstart 2.04 or higher. Sashimi cannot patch
  26. the older Enforcer at run time which means that you have to use Enforcer
  27. V37 or an equivalent like CyberGuard.
  28.  
  29.  
  30. Quick usage
  31. ===========
  32. Here's what's in my "S:User-Startup" file:
  33.  
  34. Run >NIL: MungWall NAMETAG
  35. Run >NIL: Enforcer RAWIO
  36. Run >NIL: Sashimi CONSOLE BUFK=64 NOPROMPT ASKEXIT ASKSAVE
  37.  
  38. All standard serial debugging functions are intercepted. Currently, the
  39. patch to the serial debugging input function just returns a `y'. Standard
  40. serial debugging output and Enforcer output go into Sashimi's ring buffer
  41. (the size is user-definable, with a default size of 32K), where it is
  42. noticed by the Sashimi process and written to the output window. The
  43. Sashimi process is signalled whenever a carriage return or linefeed comes
  44. through kprintf().
  45.  
  46. Sashimi has several startup options, and several runtime options:
  47.  
  48. Startup: [ON] [BUFK=n (n must be a power of 2)] [BUFFERSIZE=n] [NOPROMPT]
  49.          [QUIET] [ASKEXIT] [ASKSAVE] [TIMERON] [CONSOLE] [WINDOW=name]
  50.  
  51. Runtime: [OFF] [SAVE] [SAVEAS=name] [EMPTY]
  52.  
  53.  
  54. Startup options
  55. ===============
  56. ON              Default (not required)
  57.  
  58. BUFK=n          Changes the ring buffer size from default 32K to specified
  59.                 power-of-2 K from 4K to whatever you like, i.e. BUFK=8 will
  60.                 allocate a buffer of 8192 bytes.
  61.  
  62. BUFFERSIZE=n    Changes the ring buffer size from default 32K to specified
  63.                 buffer size, i.e. BUFFERSIZE=8000 will allocate a buffer
  64.                 of 8000 bytes.
  65.  
  66. NOPROMPT        Turns off the "Sashimi installed" prompt. This is useful if
  67.                 the Sashimi output is redirected to an AUTO CON window such
  68.                 as in conjunction with the CONSOLE option.
  69.  
  70. QUIET           Causes Sashimi to just buffer all debugging output.
  71.                 This effectively silences serial debugging output.
  72.  
  73. ASKSAVE         Cause Sashimi to ask you if you want to save the buffer
  74.                 when you exit Sashimi.  If there's nothing in the buffer,
  75.                 it won't ask.
  76.  
  77. ASKEXIT         Cause Sashimi to ask you if you *really* want to exit if
  78.                 a [Ctrl]+C signal is received.  This is good for people like
  79.                 me who might accidentally [Ctrl]+C in a Sashimi window when
  80.                 they meant to do it somewhere else.   This option should
  81.                 only be used if Sashimi has an input stream - i.e. if Sashimi
  82.                 is not run/redirected, or if Sashimi has in/out redirection
  83.                 in a CONSOLE window.
  84.  
  85. TIMERON         Cause Sashimi to wake up every 1/10 second to check for
  86.                 output. Without this option, Sashimi will just wake up every
  87.                 time a carriage return or linefeed is output.
  88.  
  89. CONSOLE         This will make Sashimi open a console output window for itself
  90.                 which all input and output will go into. Unless you provide a
  91.                 console window specifier (see WINDOW option), Sashimi will use:
  92.  
  93.                 CON:0/20/640/100/Sashimi  [Ctrl]+E=Empty  [Ctrl]+F=File  [Ctrl]+D=Reset console/AUTO/CLOSE/WAIT/INACTIVE
  94.  
  95. WINDOW=name     This option works in conjunction with the CONSOLE option and
  96.                 allows you to override the default console window specifier.
  97.  
  98.  
  99. Runtime options
  100. ===============
  101. OFF             Signals the active running copy of Sashimi to exit.
  102.  
  103. EMPTY           Finds the active running copy of Sashimi and empties its
  104.                 buffer.
  105.  
  106. SAVE            Finds the active running copy of Sashimi and saves its buffer
  107.                 as "T:sashimi.out".
  108.  
  109. SAVEAS=name     Finds the active running copy of Sashimi and saves its buffer
  110.                 as the specified file name.
  111.  
  112.  
  113. Example startup usage
  114. =====================
  115.  
  116. Sashimi ASKSAVE (in its own shell window)
  117.  
  118. Run >NIL: Sashimi >"CON:0/20/640/120/Sashimi/AUTO/CLOSE/WAIT/INACTIVE" ON NOPROMPT
  119.  
  120. Run Sashimi >ram:hits (all output redirected to a file)
  121.  
  122.  
  123. Keyboard and Break signals
  124. ==========================
  125. [Ctrl]+C: To quit Sashimi, [Ctrl]+C it (if it has its own window), send it
  126.           a [Ctrl]+C signal with the Break command, or run Sashimi a second
  127.           time with the OFF keyword.
  128.  
  129. [Ctrl]+D: This sends a control sequence to the output console to reset it.
  130.           Very handy in case garbage data has changed the character set
  131.           or the text rendering colours.
  132.  
  133. [Ctrl]+E: Tells Sashimi to empty (clear) its buffer.
  134.  
  135. [Ctrl]+F: Tells Sashimi to save its own buffer to the file "T:sashimi.out"
  136.  
  137.  
  138. Other runtime usage
  139. ===================
  140. Sashimi OFF                     ; tell active running Sashimi to try to exit
  141. Sashimi SAVE                    ; save buffer of active Sashimi
  142. Sashimi SAVEAS ram:myhits EMPTY ; save buffer as ram:myhits and clear buffer
  143.  
  144. Usually, I just hit [Ctrl]+F in the Sashimi window, and it saves its buffer
  145. as "T:sashimi.out".
  146.  
  147.  
  148. Programmer interface
  149. ====================
  150. Sorry, no programmer interface. "Sushi" had one, but I did not see much
  151. sense in replicating this functionality.
  152.  
  153.  
  154. Why "Sashimi"?
  155. ==============
  156. I got bitten by bugs in "Sushi", and not just once. Whenever the Sushi ring
  157. buffer would wrap around, there was a good chance part of the buffer would
  158. still be filled with random data when getting saved to disk. If a large
  159. amount of data would be sent through the kprintf() interface, Sushi would
  160. occasionally "hickup" and regurgitate stale data from its buffer. I took
  161. this as indications that the Sushi buffer management code was none too
  162. robust. Another thing that struck me as odd was the fact that sometimes
  163. Sushi would stop reporting incoming kprintf() output and effectively behave
  164. as if it had been stopped with [Ctrl]+C. Sushi also had tendency to block
  165. screen output when printing its buffer; it would output the buffer in a
  166. single Write() operation, causing the console window to lock the display.
  167. And while that operation was in progress, you could not suspend window output
  168. or stop it.
  169.  
  170. Sashimi tries to do better in these situations. The algorithms for
  171. maintaining the ring buffer (or FIFO) are different. And just in case there
  172. is a bug in the code, I have provided the complete tool source code.
  173.  
  174.  
  175. Author
  176. ======
  177. Sashimi was written by Olaf `Olsen' Barthel, with "Sushi" by Carolyn
  178. Scheppner as a reference. Sushi was in turn influenced by the "Reporter"
  179. and "Detective" tools written by Steve Tibbett and Christian E. Hopps.
  180.  
  181. My postal address:
  182.  
  183.    Olaf Barthel
  184.    Brabeckstrasse 35
  185.    D-30559 Hannover
  186.    Federal Republic of Germany
  187.  
  188. My e-mail address:
  189.  
  190.    olsen@sourcery.han.de
  191.  
  192.  
  193. History
  194. =======
  195.  
  196. Sashimi 1.4 (11.9.98)
  197.  
  198.     - The Sashimi RawPutChar() patch now saves and restores
  199.       the contents of A0 and A1. This is necessary since
  200.       the KPutStr() code relies upon A0 to remain unchanged
  201.       after each call to RawPutChar() [Stuart Kyzer Caie].
  202.  
  203. Sashimi 1.3 (07.04.98)
  204.  
  205.     - Updated the console window title text
  206.  
  207. Sashimi 1.2 (05.04.98)
  208.  
  209.     - Added the [Ctrl]+D console reset command.
  210.